

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>FS volumes and subvolumes &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />

  
  
    <link rel="shortcut icon" href="../../_static/favicon.ico"/>
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/underscore.js"></script>
        <script src="../../_static/doctools.js"></script>
    
    <script type="text/javascript" src="../../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../../genindex/" />
    <link rel="search" title="Search" href="../../search/" />
    <link rel="next" title="配额管理" href="../quota/" />
    <link rel="prev" title="分布式文件系统之上的应用程序最佳实践" href="../app-best-practices/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    

















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../../" class="icon icon-home"></a> &raquo;</li>
        
          <li><a href="../">Ceph 文件系统</a> &raquo;</li>
        
      <li>FS volumes and subvolumes</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="../../_sources/cephfs/fs-volumes.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../../">
          

          
            
            <img src="../../_static/logo.png" class="logo" alt="Logo"/>
          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../start/intro/">Ceph 简介</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../">Ceph 文件系统</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../#cephfs">CephFS 入门</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../#id4">管理</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../createfs/"> 创建 CephFS 文件系统</a></li>
<li class="toctree-l3"><a class="reference internal" href="../administration/"> 管理命令</a></li>
<li class="toctree-l3"><a class="reference internal" href="../multifs/"> 创建多个文件系统</a></li>
<li class="toctree-l3"><a class="reference internal" href="../add-remove-mds/"> 配备、增加、删除 MDS</a></li>
<li class="toctree-l3"><a class="reference internal" href="../standby/">术语</a></li>
<li class="toctree-l3"><a class="reference internal" href="../standby/#mds">MDS 守护进程的引用</a></li>
<li class="toctree-l3"><a class="reference internal" href="../standby/#id3">故障切换的管理</a></li>
<li class="toctree-l3"><a class="reference internal" href="../standby/#mds-standby-replay">热备的配置</a></li>
<li class="toctree-l3"><a class="reference internal" href="../standby/#mds-join-fs">配置 MDS 与文件系统的亲和性</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cache-configuration/"> MDS 缓存配置</a></li>
<li class="toctree-l3"><a class="reference internal" href="../mds-config-ref/"> MDS 配置选项</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../man/8/ceph-mds/"> ceph-mds 手册页</a></li>
<li class="toctree-l3"><a class="reference internal" href="../nfs/"> 通过 NFS 导出</a></li>
<li class="toctree-l3"><a class="reference internal" href="../app-best-practices/"> 应用最佳实践</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#"> FS 卷和子卷</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#requirements">Requirements</a></li>
<li class="toctree-l4"><a class="reference internal" href="#fs-volumes">FS Volumes</a></li>
<li class="toctree-l4"><a class="reference internal" href="#fs-subvolume-groups">FS Subvolume groups</a></li>
<li class="toctree-l4"><a class="reference internal" href="#fs-subvolumes">FS Subvolumes</a></li>
<li class="toctree-l4"><a class="reference internal" href="#cloning-snapshots">Cloning Snapshots</a></li>
<li class="toctree-l4"><a class="reference internal" href="#pinning-subvolumes-and-subvolume-groups">Pinning Subvolumes and Subvolume Groups</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../quota/"> CephFS 配额管理</a></li>
<li class="toctree-l3"><a class="reference internal" href="../health-messages/"> 健康消息</a></li>
<li class="toctree-l3"><a class="reference internal" href="../upgrading/">升级 MDS 集群</a></li>
<li class="toctree-l3"><a class="reference internal" href="../upgrading/#firefly-jewel">升级比 Firefly 老的文件系统，需过 Jewel 这个槛</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cephfs-top/"> CephFS Top 工具</a></li>
<li class="toctree-l3"><a class="reference internal" href="../snap-schedule/"> 定时快照</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cephfs-mirroring/"> CephFS 快照镜像</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../#id5">挂载 CephFS</a></li>
<li class="toctree-l2"><a class="reference internal" href="../#id6">CephFS 内幕</a></li>
<li class="toctree-l2"><a class="reference internal" href="../#id7">故障排除和灾难恢复</a></li>
<li class="toctree-l2"><a class="reference internal" href="../#id9">更多细节</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../rbd/">Ceph 块设备</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../radosgw/">Ceph 对象网关</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../architecture/">体系结构</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/developer_guide/">开发者指南</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <div class="section" id="fs-volumes-and-subvolumes">
<span id="id1"></span><h1>FS volumes and subvolumes<a class="headerlink" href="#fs-volumes-and-subvolumes" title="Permalink to this headline">¶</a></h1>
<p>A  single source of truth for CephFS exports is implemented in the volumes
module of the <a class="reference internal" href="../../glossary/#term-Ceph-Manager"><span class="xref std std-term">Ceph Manager</span></a> daemon (ceph-mgr). The OpenStack shared
file system service (<a class="reference external" href="https://github.com/openstack/manila">manila</a>), Ceph Container Storage Interface (<a class="reference external" href="https://github.com/ceph/ceph-csi">CSI</a>),
storage administrators among others can use the common CLI provided by the
ceph-mgr volumes module to manage the CephFS exports.</p>
<p>The ceph-mgr volumes module implements the following file system export
abstactions:</p>
<ul class="simple">
<li><p>FS volumes, an abstraction for CephFS file systems</p></li>
<li><p>FS subvolumes, an abstraction for independent CephFS directory trees</p></li>
<li><p>FS subvolume groups, an abstraction for a directory level higher than FS
subvolumes to effect policies (e.g., <a class="reference internal" href="../file-layouts/"><span class="doc">文件布局</span></a>) across a
set of subvolumes</p></li>
</ul>
<p>Some possible use-cases for the export abstractions:</p>
<ul class="simple">
<li><p>FS subvolumes used as manila shares or CSI volumes</p></li>
<li><p>FS subvolume groups used as manila share groups</p></li>
</ul>
<div class="section" id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p>Nautilus (14.2.x) or a later version of Ceph</p></li>
<li><p>Cephx client user (see <a class="reference internal" href="../../rados/operations/user-management/"><span class="doc">用户管理</span></a>) with
the following minimum capabilities:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mon</span> <span class="s1">&#39;allow r&#39;</span>
<span class="n">mgr</span> <span class="s1">&#39;allow rw&#39;</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="fs-volumes">
<h2>FS Volumes<a class="headerlink" href="#fs-volumes" title="Permalink to this headline">¶</a></h2>
<p>Create a volume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs volume create &lt;vol_name&gt; [&lt;placement&gt;]
</pre></div>
</div>
<p>This creates a CephFS file system and its data and metadata pools. It can also
try to create MDSes for the filesystem using the enabled ceph-mgr orchestrator
module (see <a class="reference internal" href="../../mgr/orchestrator/"><span class="doc">Orchestrator CLI</span></a>), e.g. rook.</p>
<p>&lt;vol_name&gt; is the volume name (an arbitrary string), and</p>
<p>&lt;placement&gt; is an optional string signifying which hosts should have NFS Ganesha
daemon containers running on them and, optionally, the total number of NFS
Ganesha daemons the cluster (should you want to have more than one NFS Ganesha
daemon running per node). For example, the following placement string means
“deploy NFS Ganesha daemons on nodes host1 and host2 (one daemon per host):</p>
<blockquote>
<div><p>“host1,host2”</p>
</div></blockquote>
<p>and this placement specification says to deploy two NFS Ganesha daemons each
on nodes host1 and host2 (for a total of four NFS Ganesha daemons in the
cluster):</p>
<blockquote>
<div><p>“4 host1,host2”</p>
</div></blockquote>
<p>For more details on placement specification refer to the <a class="reference internal" href="../../cephadm/services/#orchestrator-cli-service-spec"><span class="std std-ref">Service Specification</span></a>,
but keep in mind that specifying the placement via a YAML file is not supported.</p>
<p>Remove a volume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs volume rm &lt;vol_name&gt; [--yes-i-really-mean-it]
</pre></div>
</div>
<p>This removes a file system and its data and metadata pools. It also tries to
remove MDSes using the enabled ceph-mgr orchestrator module.</p>
<p>List volumes using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs volume ls
</pre></div>
</div>
</div>
<div class="section" id="fs-subvolume-groups">
<h2>FS Subvolume groups<a class="headerlink" href="#fs-subvolume-groups" title="Permalink to this headline">¶</a></h2>
<p>Create a subvolume group using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup create &lt;vol_name&gt; &lt;group_name&gt; [--pool_layout &lt;data_pool_name&gt;] [--uid &lt;uid&gt;] [--gid &lt;gid&gt;] [--mode &lt;octal_mode&gt;]
</pre></div>
</div>
<p>The command succeeds even if the subvolume group already exists.</p>
<p>When creating a subvolume group you can specify its data pool layout (see
<a class="reference internal" href="../file-layouts/"><span class="doc">文件布局</span></a>), uid, gid, and file mode in octal numerals. By default, the
subvolume group is created with an octal file mode ‘755’, uid ‘0’, gid ‘0’ and data pool
layout of its parent directory.</p>
<p>Remove a subvolume group using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup rm &lt;vol_name&gt; &lt;group_name&gt; [--force]
</pre></div>
</div>
<p>The removal of a subvolume group fails if it is not empty or non-existent.
‘–force’ flag allows the non-existent subvolume group remove command to succeed.</p>
<p>Fetch the absolute path of a subvolume group using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup getpath &lt;vol_name&gt; &lt;group_name&gt;
</pre></div>
</div>
<p>List subvolume groups using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup ls &lt;vol_name&gt;
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Subvolume group snapshot feature is no longer supported in mainline CephFS (existing group
snapshots can still be listed and deleted)</p>
</div>
<p>Remove a snapshot of a subvolume group using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup snapshot rm &lt;vol_name&gt; &lt;group_name&gt; &lt;snap_name&gt; [--force]
</pre></div>
</div>
<p>Using the ‘–force’ flag allows the command to succeed that would otherwise
fail if the snapshot did not exist.</p>
<p>List snapshots of a subvolume group using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup snapshot ls &lt;vol_name&gt; &lt;group_name&gt;
</pre></div>
</div>
</div>
<div class="section" id="fs-subvolumes">
<h2>FS Subvolumes<a class="headerlink" href="#fs-subvolumes" title="Permalink to this headline">¶</a></h2>
<p>Create a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume create &lt;vol_name&gt; &lt;subvol_name&gt; [--size &lt;size_in_bytes&gt;] [--group_name &lt;subvol_group_name&gt;] [--pool_layout &lt;data_pool_name&gt;] [--uid &lt;uid&gt;] [--gid &lt;gid&gt;] [--mode &lt;octal_mode&gt;] [--namespace-isolated]
</pre></div>
</div>
<p>The command succeeds even if the subvolume already exists.</p>
<p>When creating a subvolume you can specify its subvolume group, data pool layout,
uid, gid, file mode in octal numerals, and size in bytes. The size of the subvolume is
specified by setting a quota on it (see <a class="reference internal" href="../quota/"><span class="doc">配额管理</span></a>). The subvolume can be
created in a separate RADOS namespace by specifying –namespace-isolated option. By
default a subvolume is created within the default subvolume group, and with an octal file
mode ‘755’, uid of its subvolume group, gid of its subvolume group, data pool layout of
its parent directory and no size limit.</p>
<p>Remove a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume rm &lt;vol_name&gt; &lt;subvol_name&gt; [--group_name &lt;subvol_group_name&gt;] [--force] [--retain-snapshots]
</pre></div>
</div>
<p>The command removes the subvolume and its contents. It does this in two steps.
First, it moves the subvolume to a trash folder, and then asynchronously purges
its contents.</p>
<p>The removal of a subvolume fails if it has snapshots, or is non-existent.
‘–force’ flag allows the non-existent subvolume remove command to succeed.</p>
<p>A subvolume can be removed retaining existing snapshots of the subvolume using the
‘–retain-snapshots’ option. If snapshots are retained, the subvolume is considered
empty for all operations not involving the retained snapshots.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Snapshot retained subvolumes can be recreated using ‘ceph fs subvolume create’</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Retained snapshots can be used as a clone source to recreate the subvolume, or clone to a newer subvolume.</p>
</div>
<p>Resize a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume resize &lt;vol_name&gt; &lt;subvol_name&gt; &lt;new_size&gt; [--group_name &lt;subvol_group_name&gt;] [--no_shrink]
</pre></div>
</div>
<p>The command resizes the subvolume quota using the size specified by ‘new_size’.
‘–no_shrink’ flag prevents the subvolume to shrink below the current used size of the subvolume.</p>
<p>The subvolume can be resized to an infinite size by passing ‘inf’ or ‘infinite’ as the new_size.</p>
<p>Authorize cephx auth IDs, the read/read-write access to fs subvolumes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume authorize &lt;vol_name&gt; &lt;sub_name&gt; &lt;auth_id&gt; [--group_name=&lt;group_name&gt;] [--access_level=&lt;access_level&gt;]
</pre></div>
</div>
<p>The ‘access_level’ takes ‘r’ or ‘rw’ as value.</p>
<p>Deauthorize cephx auth IDs, the read/read-write access to fs subvolumes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume deauthorize &lt;vol_name&gt; &lt;sub_name&gt; &lt;auth_id&gt; [--group_name=&lt;group_name&gt;]
</pre></div>
</div>
<p>List cephx auth IDs authorized to access fs subvolume:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume authorized_list &lt;vol_name&gt; &lt;sub_name&gt; [--group_name=&lt;group_name&gt;]
</pre></div>
</div>
<p>Evict fs clients based on auth ID and subvolume mounted:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume evict &lt;vol_name&gt; &lt;sub_name&gt; &lt;auth_id&gt; [--group_name=&lt;group_name&gt;]
</pre></div>
</div>
<p>Fetch the absolute path of a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume getpath &lt;vol_name&gt; &lt;subvol_name&gt; [--group_name &lt;subvol_group_name&gt;]
</pre></div>
</div>
<p>Fetch the metadata of a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume info &lt;vol_name&gt; &lt;subvol_name&gt; [--group_name &lt;subvol_group_name&gt;]
</pre></div>
</div>
<p>The output format is json and contains fields as follows.</p>
<ul class="simple">
<li><p>atime: access time of subvolume path in the format “YYYY-MM-DD HH:MM:SS”</p></li>
<li><p>mtime: modification time of subvolume path in the format “YYYY-MM-DD HH:MM:SS”</p></li>
<li><p>ctime: change time of subvolume path in the format “YYYY-MM-DD HH:MM:SS”</p></li>
<li><p>uid: uid of subvolume path</p></li>
<li><p>gid: gid of subvolume path</p></li>
<li><p>mode: mode of subvolume path</p></li>
<li><p>mon_addrs: list of monitor addresses</p></li>
<li><p>bytes_pcent: quota used in percentage if quota is set, else displays “undefined”</p></li>
<li><p>bytes_quota: quota size in bytes if quota is set, else displays “infinite”</p></li>
<li><p>bytes_used: current used size of the subvolume in bytes</p></li>
<li><p>created_at: time of creation of subvolume in the format “YYYY-MM-DD HH:MM:SS”</p></li>
<li><p>data_pool: data pool the subvolume belongs to</p></li>
<li><p>path: absolute path of a subvolume</p></li>
<li><p>type: subvolume type indicating whether it’s clone or subvolume</p></li>
<li><p>pool_namespace: RADOS namespace of the subvolume</p></li>
<li><p>features: features supported by the subvolume</p></li>
<li><p>state: current state of the subvolume</p></li>
</ul>
<p>If a subvolume has been removed retaining its snapshots, the output only contains fields as follows.</p>
<ul class="simple">
<li><p>type: subvolume type indicating whether it’s clone or subvolume</p></li>
<li><p>features: features supported by the subvolume</p></li>
<li><p>state: current state of the subvolume</p></li>
</ul>
<p>The subvolume “features” are based on the internal version of the subvolume and is a list containing
a subset of the following features,</p>
<ul class="simple">
<li><p>“snapshot-clone”: supports cloning using a subvolumes snapshot as the source</p></li>
<li><p>“snapshot-autoprotect”: supports automatically protecting snapshots, that are active clone sources, from deletion</p></li>
<li><p>“snapshot-retention”: supports removing subvolume contents, retaining any existing snapshots</p></li>
</ul>
<p>The subvolume “state” is based on the current state of the subvolume and contains one of the following values.</p>
<ul class="simple">
<li><p>“complete”: subvolume is ready for all operations</p></li>
<li><p>“snapshot-retained”: subvolume is removed but its snapshots are retained</p></li>
</ul>
<p>List subvolumes using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume ls &lt;vol_name&gt; [--group_name &lt;subvol_group_name&gt;]
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>subvolumes that are removed but have snapshots retained, are also listed.</p>
</div>
<p>Create a snapshot of a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot create &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; [--group_name &lt;subvol_group_name&gt;]
</pre></div>
</div>
<p>Remove a snapshot of a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot rm &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; [--group_name &lt;subvol_group_name&gt;] [--force]
</pre></div>
</div>
<p>Using the ‘–force’ flag allows the command to succeed that would otherwise
fail if the snapshot did not exist.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>if the last snapshot within a snapshot retained subvolume is removed, the subvolume is also removed</p>
</div>
<p>List snapshots of a subvolume using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot ls &lt;vol_name&gt; &lt;subvol_name&gt; [--group_name &lt;subvol_group_name&gt;]
</pre></div>
</div>
<p>Fetch the metadata of a snapshot using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot info &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; [--group_name &lt;subvol_group_name&gt;]
</pre></div>
</div>
<p>The output format is json and contains fields as follows.</p>
<ul class="simple">
<li><p>created_at: time of creation of snapshot in the format “YYYY-MM-DD HH:MM:SS:ffffff”</p></li>
<li><p>data_pool: data pool the snapshot belongs to</p></li>
<li><p>has_pending_clones: “yes” if snapshot clone is in progress otherwise “no”</p></li>
<li><p>size: snapshot size in bytes</p></li>
</ul>
</div>
<div class="section" id="cloning-snapshots">
<h2>Cloning Snapshots<a class="headerlink" href="#cloning-snapshots" title="Permalink to this headline">¶</a></h2>
<p>Subvolumes can be created by cloning subvolume snapshots. Cloning is an asynchronous operation involving copying
data from a snapshot to a subvolume. Due to this bulk copy nature, cloning is currently inefficient for very huge
data sets.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Removing a snapshot (source subvolume) would fail if there are pending or in progress clone operations.</p>
</div>
<p>Protecting snapshots prior to cloning was a pre-requisite in the Nautilus release, and the commands to protect/unprotect
snapshots were introduced for this purpose. This pre-requisite, and hence the commands to protect/unprotect, is being
deprecated in mainline CephFS, and may be removed from a future release.</p>
<dl class="simple">
<dt>The commands being deprecated are:</dt><dd><p>$ ceph fs subvolume snapshot protect &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; [–group_name &lt;subvol_group_name&gt;]
$ ceph fs subvolume snapshot unprotect &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; [–group_name &lt;subvol_group_name&gt;]</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Using the above commands would not result in an error, but they serve no useful function.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Use subvolume info command to fetch subvolume metadata regarding supported “features” to help decide if protect/unprotect of snapshots is required, based on the “snapshot-autoprotect” feature availability.</p>
</div>
<p>To initiate a clone operation use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot clone &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; &lt;target_subvol_name&gt;
</pre></div>
</div>
<p>If a snapshot (source subvolume) is a part of non-default group, the group name needs to be specified as per:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot clone &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; &lt;target_subvol_name&gt; --group_name &lt;subvol_group_name&gt;
</pre></div>
</div>
<p>Cloned subvolumes can be a part of a different group than the source snapshot (by default, cloned subvolumes are created in default group). To clone to a particular group use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot clone &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; &lt;target_subvol_name&gt; --target_group_name &lt;subvol_group_name&gt;
</pre></div>
</div>
<p>Similar to specifying a pool layout when creating a subvolume, pool layout can be specified when creating a cloned subvolume. To create a cloned subvolume with a specific pool layout use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot clone &lt;vol_name&gt; &lt;subvol_name&gt; &lt;snap_name&gt; &lt;target_subvol_name&gt; --pool_layout &lt;pool_layout&gt;
</pre></div>
</div>
<p>Configure maximum number of concurrent clones. The default is set to 4:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph config set mgr mgr/volumes/max_concurrent_clones &lt;value&gt;
</pre></div>
</div>
<p>To check the status of a clone operation use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs clone status &lt;vol_name&gt; &lt;clone_name&gt; [--group_name &lt;group_name&gt;]
</pre></div>
</div>
<p>A clone can be in one of the following states:</p>
<ol class="arabic simple">
<li><p><cite>pending</cite>     : Clone operation has not started</p></li>
<li><p><cite>in-progress</cite> : Clone operation is in progress</p></li>
<li><p><cite>complete</cite>    : Clone operation has successfully finished</p></li>
<li><p><cite>failed</cite>      : Clone operation has failed</p></li>
</ol>
<p>Sample output from an <cite>in-progress</cite> clone operation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot clone cephfs subvol1 snap1 clone1
$ ceph fs clone status cephfs clone1
{
  &quot;status&quot;: {
    &quot;state&quot;: &quot;in-progress&quot;,
    &quot;source&quot;: {
      &quot;volume&quot;: &quot;cephfs&quot;,
      &quot;subvolume&quot;: &quot;subvol1&quot;,
      &quot;snapshot&quot;: &quot;snap1&quot;
    }
  }
}
</pre></div>
</div>
<p>(NOTE: since <cite>subvol1</cite> is in default group, <cite>source</cite> section in <cite>clone status</cite> does not include group name)</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Cloned subvolumes are accessible only after the clone operation has successfully completed.</p>
</div>
<p>For a successful clone operation, <cite>clone status</cite> would look like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs clone status cephfs clone1
{
  &quot;status&quot;: {
    &quot;state&quot;: &quot;complete&quot;
  }
}
</pre></div>
</div>
<p>or <cite>failed</cite> state when clone is unsuccessful.</p>
<p>On failure of a clone operation, the partial clone needs to be deleted and the clone operation needs to be retriggered.
To delete a partial clone use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume rm &lt;vol_name&gt; &lt;clone_name&gt; [--group_name &lt;group_name&gt;] --force
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Cloning only synchronizes directories, regular files and symbolic links. Also, inode timestamps (access and
modification times) are synchronized upto seconds granularity.</p>
</div>
<p>An <cite>in-progress</cite> or a <cite>pending</cite> clone operation can be canceled. To cancel a clone operation use the <cite>clone cancel</cite> command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs clone cancel &lt;vol_name&gt; &lt;clone_name&gt; [--group_name &lt;group_name&gt;]
</pre></div>
</div>
<p>On successful cancelation, the cloned subvolume is moved to <cite>canceled</cite> state:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume snapshot clone cephfs subvol1 snap1 clone1
$ ceph fs clone cancel cephfs clone1
$ ceph fs clone status cephfs clone1
{
  &quot;status&quot;: {
    &quot;state&quot;: &quot;canceled&quot;,
    &quot;source&quot;: {
      &quot;volume&quot;: &quot;cephfs&quot;,
      &quot;subvolume&quot;: &quot;subvol1&quot;,
      &quot;snapshot&quot;: &quot;snap1&quot;
    }
  }
}
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The canceled cloned can be deleted by using –force option in <cite>fs subvolume rm</cite> command.</p>
</div>
</div>
<div class="section" id="pinning-subvolumes-and-subvolume-groups">
<span id="subvol-pinning"></span><h2>Pinning Subvolumes and Subvolume Groups<a class="headerlink" href="#pinning-subvolumes-and-subvolume-groups" title="Permalink to this headline">¶</a></h2>
<p>Subvolumes and subvolume groups can be automatically pinned to ranks according
to policies. This can help distribute load across MDS ranks in predictable and
stable ways.  Review <a class="reference internal" href="../multimds/#cephfs-pinning"><span class="std std-ref">手动将目录树插入特定的 rank</span></a> and <a class="reference internal" href="../multimds/#cephfs-ephemeral-pinning"><span class="std std-ref">设置子树分区策略</span></a>
for details on how pinning works.</p>
<p>Pinning is configured by:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup pin &lt;vol_name&gt; &lt;group_name&gt; &lt;pin_type&gt; &lt;pin_setting&gt;
</pre></div>
</div>
<p>or for subvolumes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolume pin &lt;vol_name&gt; &lt;group_name&gt; &lt;pin_type&gt; &lt;pin_setting&gt;
</pre></div>
</div>
<p>Typically you will want to set subvolume group pins. The <code class="docutils literal notranslate"><span class="pre">pin_type</span></code> may be
one of <code class="docutils literal notranslate"><span class="pre">export</span></code>, <code class="docutils literal notranslate"><span class="pre">distributed</span></code>, or <code class="docutils literal notranslate"><span class="pre">random</span></code>. The <code class="docutils literal notranslate"><span class="pre">pin_setting</span></code>
corresponds to the extended attributed “value” as in the pinning documentation
referenced above.</p>
<p>So, for example, setting a distributed pinning strategy on a subvolume group:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph fs subvolumegroup pin cephfilesystem-a csi distributed 1
</pre></div>
</div>
<p>Will enable distributed subtree partitioning policy for the “csi” subvolume
group.  This will cause every subvolume within the group to be automatically
pinned to one of the available ranks on the file system.</p>
</div>
</div>



           </div>
           
          </div>
          <footer>
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
        <a href="../quota/" class="btn btn-neutral float-right" title="配额管理" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
        <a href="../app-best-practices/" class="btn btn-neutral float-left" title="分布式文件系统之上的应用程序最佳实践" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>
        &#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).

    </p>
  </div> 

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>